********************************************************************************

                   Debugging Tips for DrawSprocket Developers
                  
                        Last Updated: October 28, 1998

********************************************************************************

This file contains some useful tips for debugging your games that are using
DrawSprocket. It is compiled from questions and issues that are brought to our
attention regularly, so please read and use this information before reporting
problems to Apple.

If you find that none of the suggestions here address the problem, send a bug
report using the bug reporter on Apple Developer Connection:

<http://developer.apple.com/bugreporter/index.html>

-  Use the DrawSprocketDebugLib for all your development.  It will flag
   problems by dropping you into MacsBug with warning messages that describe
   what you did wrong.

-	 Make sure you have the latest DrawSprocket. Verify this by going to
   <http://developer.apple.com/dev/games> and comparing the version of what
   you have against what is available.

-  Check for multiple copies of DrawSprocket on your machine.  You may be
   running against one you aren't expecting, and it may be older.
	
-  Use debug mode to stop DSp from gamma fading and showing the blanking
   window.  This can be done programmatically with the DSpSetDebugMode() call,
   or by creating a folder in the same directory as your game called
   "DSpSetDebugMode".	Debug mode only works with the debug build of DSp, and
   comes in *very* useful when you drop into the debugger when the screen is
   faded out.

-  Check the return codes from all DrawSprocket calls.  DSp returns valuable
   information in the return codes, and your game really shouldn't ignore
   them. If you ignore them and something bad happens, you're probably going
   to crash.
	
-  Compare how you are doing things with how the available sample source
   code does things.  You might spot a subtlety that you missed before.
	
-  Make sure your application has a large enough heap to run AND allocate
   your graphics pages.  To roughly calculate the amount of memory used by DSp
   (on your behalf), figure:
	
      page_size = width * height * pixel_byte_size
      allocated memory = ( page_count - 1 ) * page_size
		
   This is a generalization, but should handle the worst case scenario.  If
   you are allocating a 640x480 8 bit context with a page count, you would get:
	
      page_size = 640 * 480 * 1 = 300k
      allocated memory = ( 2 - 1 ) * 300k, or 300k.
		
   Additional memory is required for AltBuffers, etc.
	
-  Try eliminating sections of code until you can track down a statement that
   causes the bad behavior to manifest.  For example, if you find that you are
   getting an address exception at a given point in your program, try
   eliminating code sections from the execution path until the address
   exception doesn't occur.  This will often lead you directly to a memory
   trashing bug.
	
-  If you have installed the Display Manger manually (pre 7.5.3 systems), make
   sure you are using the "Display Library" shared library, and not the
   "DisplayLib" shared library.  "DisplayLib", while having the same file name
   as the desired code fragment, is actually a linker stub library.  It is
   supposed to have a file type of 'stub', but it doesn't, and that's wrong,
	  and CFM will try to link your program to it.

-  If you set the page flipping flag in your application, test your code on a
   machine capable of page flipping before you ship.  Some applications have
   shipped with bugs because they did not do proper testing.  Applications should
   make sure they call DSpContext_GetBackBuffer every frame, and also ensure that
   they properly update any underlay buffers using DSpAltBuffer_InvalRect.

   A good machine to test is any 7500/7600/8500/8600 with 4 megabytes of VRAM.

-  If you have at least version 1.1.3 of DrawSprocket you can call
   DSpUserSelectContext() on a single-monitor system if you turn on debug mode.
